<SECTION>
<FILE>gtkmultiselection</FILE>
-<TITLE>GtkMultiSeledction</TITLE>
+<TITLE>GtkMultiSelection</TITLE>
GtkMultiSelection
gtk_multi_selection_new
gtk_multi_selection_get_model
* @see_also: #GtkColumnView
*
* GtkColumnViewColumn represents the columns being added to #GtkColumnView.
+ *
+ * Columns have a title, and can optionally have a header menu set
+ * with gtk_column_view_column_set_header_menu().
+ *
+ * A sorter can be associated with a column using
+ * gtk_column_view_column_set_sorter(), to let users influence sorting by
+ * clicking on the column header.
*/
struct _GtkColumnViewColumn
*
* This sorter can be made active by clicking on the column
* header, or by calling gtk_column_view_sort_by_column().
+ *
+ * See gtk_column_view_get_sorter() for the necessary steps
+ * for setting up customizable sorting for #GtkColumnView.
*/
void
gtk_column_view_column_set_sorter (GtkColumnViewColumn *self,
* It presents a #GListModel and fills it asynchronously with the #GFileInfos
* returned from that function.
*
- * Enumeration will start automatically when a the GtkDirectoryList:file property
+ * Enumeration will start automatically when a the #GtkDirectoryList:file property
* is set.
*
- * While the #GtkDirectoryList is being filled, the GtkDirectoryList:loading
+ * While the #GtkDirectoryList is being filled, the #GtkDirectoryList:loading
* property will be set to %TRUE. You can listen to that property if you want
* to show information like a #GtkSpinner or a "Loading..." text.
- * If loading fails at any point, the GtkDirectoryList:error property will be set
- * to give more indication about the failure.
+ *
+ * If loading fails at any point, the #GtkDirectoryList:error property will be
+ * set to give more indication about the failure.
*
* The #GFileInfos returned from a #GtkDirectoryList have the "standard::file"
* attribute set to the #GFile they refer to. This way you can get at the file
* that is referred to in the same way you would via g_file_enumerator_get_child().
* This means you do not need access to the #GtkDirectoryList but can access
- * the #GFile directly from the #GFileInfo when operating with a #GtkListView or
- * similar.
+ * the #GFile directly from the #GFileInfo when operating with a #GtkListView
+ * or similar.
*/
/* random number that everyone else seems to use, too */
*
* Returns %TRUE if the children enumeration is currently in
* progress.
+ *
* Files will be added to @self from time to time while loading is
* going on. The order in which are added is undefined and may change
* inbetween runs.
*
* The options are given to GtkDropDown in the form of #GListModel,
* and how the individual options are represented is determined by
- * a #GtkListItemFactory. The default factory displays simple strings,
- * and expects to obtain these from the model by evaluating an expression
- * that has to be provided via gtk_drop_down_set_expression().
+ * a #GtkListItemFactory. The default factory displays simple strings.
*
* GtkDropDown knows how to obtain strings from the items in a
* #GtkStringList; for other models, you have to provide an expression
- * to find the strings.
+ * to find the strings via gtk_drop_down_set_expression().
*
* GtkDropDown can optionally allow search in the popup, which is
* useful if the list of options is long. To enable the search entry,
gobject_class->dispose = gtk_multi_selection_dispose;
/**
- * GtkMultiSelection:model
+ * GtkMultiSelection:model:
*
* The list managed by this selection
*/
* @Title: GtkNoSelection
* @see_also: #GtkSelectionModel
*
- * GtkNoSelection is an implementation of the #GtkSelectionModel interface
+ * GtkNoSelection is an implementation of the #GtkSelectionModel interface
* that does not allow selecting anything.
*
* This model is meant to be used as a simple wrapper to #GListModels when a
* @Short_description: An extension of the list model interface that handles selections
* @See_also: #GListModel, #GtkSingleSelection
*
- * #GtkSelectionModel is an interface that extends the #GListModel interface by adding
- * support for selections. This support is then used by widgets using list models to add
- * the ability to select and unselect various items.
+ * #GtkSelectionModel is an interface that extends the #GListModel interface by
+ * adding support for selections. This support is then used by widgets using list
+ * models to add the ability to select and unselect various items.
*
- * GTK provides default implementations of the mode common selection modes such as
- * #GtkSingleSelection, so you will only need to implement this interface if you want
- * detailed control about how selections should be handled.
+ * GTK provides default implementations of the most common selection modes such
+ * as #GtkSingleSelection, so you will only need to implement this interface if
+ * you want detailed control about how selections should be handled.
*
- * A #GtkSelectionModel supports a single boolean per item indicating if an item is selected
- * or not. This can be queried via gtk_selection_model_is_selected(). When the selected
- * state of one or more items changes, the model will emit the
+ * A #GtkSelectionModel supports a single boolean per item indicating if an item
+ * is selected or not. This can be queried via gtk_selection_model_is_selected().
+ * When the selected state of one or more items changes, the model will emit the
* #GtkSelectionModel::selection-changed signal by calling the
- * gtk_selection_model_selection_changed() function. The positions given in that signal
- * may have their selection state changed, though that is not a requirement.
- * If new items added to the model via the #GListModel::items-changed signal are selected
- * or not is up to the implementation.
+ * gtk_selection_model_selection_changed() function. The positions given in that
+ * signal may have their selection state changed, though that is not a requirement.
+ * If new items added to the model via the #GListModel::items-changed signal are
+ * selected or not is up to the implementation.
*
* Note that items added via #GListModel::items-changed may already be selected
* and no #GtkSelectionModel::selection-changed will be emitted for them. So to
* track which items are selected, it is necessary to listen to both signals.
*
- * Additionally, the interface can expose functionality to select and unselect items.
- * If these functions are implemented, GTK's list widgets will allow users to select and
- * unselect items. However, #GtkSelectionModels are free to only implement them
- * partially or not at all. In that case the widgets will not support the unimplemented
- * operations.
+ * Additionally, the interface can expose functionality to select and unselect
+ * items. If these functions are implemented, GTK's list widgets will allow users
+ * to select and unselect items. However, #GtkSelectionModels are free to only
+ * implement them partially or not at all. In that case the widgets will not
+ * support the unimplemented operations.
*
- * When selecting or unselecting is supported by a model, the return values of the
- * selection functions do NOT indicate if selection or unselection happened. They are
- * only meant to indicate complete failure, like when this mode of selecting is not
- * supported by the model.
+ * When selecting or unselecting is supported by a model, the return values of
+ * the selection functions do *not* indicate if selection or unselection happened.
+ * They are only meant to indicate complete failure, like when this mode of
+ * selecting is not supported by the model.
*
- * Selections may happen asynchronously, so the only reliable way to find out when an
- * item was selected is to listen to the signals that indicate selection.
+ * Selections may happen asynchronously, so the only reliable way to find out
+ * when an item was selected is to listen to the signals that indicate selection.
*/
G_DEFINE_INTERFACE (GtkSelectionModel, gtk_selection_model, G_TYPE_LIST_MODEL)
* Emitted when the selection state of some of the items in @model changes.
*
* Note that this signal does not specify the new selection state of the items,
- * they need to be queried manually.
+ * they need to be queried manually.
* It is also not necessary for a model to change the selection state of any of
* the items in the selection model, though it would be rather useless to emit
* such a signal.
* @position: start of the queired range
* @n_items: number of items in the queried range
*
- * Gets a set containing a set where the values in the range [position,
- * position + n_items) match the selected state of the items in that range.
+ * Gets a set containing a set where the values in the range `[position,
+ * position + n_items)` match the selected state of the items in that range.
* All values outside that range are undefined.
*
* This function is an optimization for gtk_selection_model_get_selection() when
* you are only interested in part of the model's selected state. A common use
- * case is in response to the :selection-changed signal.
+ * case is in response to the #GtkSelectionModel::selection-changed signal.
*
* Returns: A #GtkBitset that matches the selection state for the given state
* with all other values being undefined.
* are more likely to implement support for those.
*
* Requests that the selection state of all positions set in @mask be
- * updated to the respecitve value in the @selected bitmask.
+ * updated to the respecitve value in the @selected bitmask.
*
* In pseudocode, it would look something like this:
*
* @n_items: the number of changed items
*
* Helper function for implementations of #GtkSelectionModel.
- * Call this when a the selection changes to emit the ::selection-changed
- * signal.
+ * Call this when a the selection changes to emit the
+ * #GtkSelectionModel::selection-changed signal.
*/
void
gtk_selection_model_selection_changed (GtkSelectionModel *model,
* The ::setup signal is emitted when a new listitem has been created and
* needs to be setup for use. It is the first signal emitted for every listitem.
*
- * The GtkSignalListItemFactory::teardown signal is the opposite of this signal
+ * The #GtkSignalListItemFactory::teardown signal is the opposite of this signal
* and can be used to undo everything done in this signal.
*/
signals[SETUP] =
* @self: The #GtkSignalListItemFactory
* @listitem: The #GtkListItem to bind
*
- * The ::bind signal is emitted when a new GtkListItem:item has been set
+ * The ::bind signal is emitted when a new #GtkListItem:item has been set
* on the @listitem and should be bound for use.
*
* After this signal was emitted, the listitem might be shown in a #GtkListView
* or other list widget.
*
- * The GtkSignalListItemFactory::unbind signal is the opposite of this signal
+ * The #GtkSignalListItemFactory::unbind signal is the opposite of this signal
* and can be used to undo everything done in this signal.
*/
signals[BIND] =
* @listitem: The #GtkListItem to unbind
*
* The ::unbind signal is emitted when a listitem has been removed from use
- * in a list widget and its new GtkListItem:item is about to be unset.
+ * in a list widget and its new #GtkListItem:item is about to be unset.
*
- * This signal is the opposite of the GtkSignalListItemFactory::bind signal
+ * This signal is the opposite of the #GtkSignalListItemFactory::bind signal
* and should be used to undo everything done in that signal.
*/
signals[UNBIND] =
* The ::teardown signal is emitted when a listitem is about to be destroyed.
* It is the last signal ever emitted for this @listitem.
*
- * This signal is the opposite of the GtkSignalListItemFactory::setup signal
+ * This signal is the opposite of the #GtkSignalListItemFactory::setup signal
* and should be used to undo everything done in that signal.
*/
signals[TEARDOWN] =
* used by list widgets in GTK.
*
* Note that the selection is *persistent* -- if the selected item is removed
- * and re-added in the same ::items-changed emission, it stays selected. In
- * particular, this means that changing the sort order of an underlying sort
+ * and re-added in the same #GListModel::items-changed emission, it stays selected.
+ * In particular, this means that changing the sort order of an underlying sort
* model will preserve the selection.
*/
struct _GtkSingleSelection
* @self: a #GtkSingleSelection
* @position: the item to select or #GTK_INVALID_LIST_POSITION
*
- * Selects the item at the given position. If the list does not have an item at
- * @position or #GTK_INVALID_LIST_POSITION is given, the behavior depends on the
- * value of the GtkSingleSelection:autoselect property: If it is set, no change
- * will occur and the old item will stay selected. If it is unset, the selection
- * will be unset and no item will be selected.
+ * Selects the item at the given position.
+ *
+ * If the list does not have an item at @position or
+ * #GTK_INVALID_LIST_POSITION is given, the behavior depends on the
+ * value of the #GtkSingleSelection:autoselect property: If it is set,
+ * no change will occur and the old item will stay selected. If it is
+ * unset, the selection will be unset and no item will be selected.
**/
void
gtk_single_selection_set_selected (GtkSingleSelection *self,
/**
* gtk_single_selection_get_selected_item:
* @self: a #GtkSingleSelection
- *
- * Gets the selected item. If no item is selected, %NULL is returned.
+ *
+ * Gets the selected item.
+ *
+ * If no item is selected, %NULL is returned.
*
* Returns: (transfer none): The selected item
*/
* If %TRUE, unselecting the current item via
* gtk_selection_model_unselect_item() is supported.
*
- * Note that setting GtkSingleSelection:autoselect will cause the
+ * Note that setting #GtkSingleSelection:autoselect will cause the
* unselecting to not work, so it practically makes no sense to set
- * both at the same time the same time..
+ * both at the same time the same time.
**/
void
gtk_single_selection_set_can_unselect (GtkSingleSelection *self,
* Changes @self by removing @n_removals strings and adding @additions
* to it.
*
- * This function is more efficient than gtk_string_list_insert() and
+ * This function is more efficient than gtk_string_list_append() and
* gtk_string_list_remove(), because it only emits
* #GListModel::items-changed once for the change.
*
- * This function takes a ref on each item in @additions.
+ * This function copies the strings in @additions.
*
* The parameters @position and @n_removals must be correct (ie:
* @position + @n_removals must be less than or equal to the length
projects / gtk4.git / commitdiff